Repository navigation
mdbx: Cursor.GetBatch — batched cursor reads (one cgo call per N records, ~3.5x faster scans) - #240
AskAlexSharov wants to merge 28 commits into
Conversation
…records Full-table iteration through Cursor.Get pays the fixed Go->C call overhead once per record, which dominates the cost of small-record scans. GetBatch moves the loop into C: one cgo call fills a reusable C-allocated buffer of MDBX_val pairs (C memory so the cgo runtime never scans it for Go pointers), and Go reads the results as zero-copy views. Benchmark (100k records, 12-byte keys/values, darwin/arm64): Get_Next 34.2 ns/record GetBatch_64 10.3 ns/record GetBatch_256 9.7 ns/record GetBatch_1024 9.7 ns/record ~3.5x faster full scans; the returned slices have the same lifetime rules as Cursor.Get (valid until txn end / next batch reusing the buffer).
3052e1f to
6a95848
Compare
There was a problem hiding this comment.
Pull request overview
Adds a batched cursor-scan API to reduce per-record cgo overhead by moving the inner mdbx_cursor_get loop into C and returning zero-copy key/value views via a reusable C-allocated buffer.
Changes:
- Add
mdbxgo_cursor_get_batchC helper that retrieves up to N(key,value)pairs per call. - Introduce
GetBatchBuffer+Cursor.GetBatchGo API backed by C-allocatedMDBX_valstorage. - Add correctness/no-alloc tests and a benchmark comparing
Get/NextvsGetBatch.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| mdbx/mdbxgo.h | Declares the new mdbxgo_cursor_get_batch helper and documents its contract. |
| mdbx/mdbxgo.c | Implements the batched loop around mdbx_cursor_get and writes results into a caller-provided MDBX_val pair buffer. |
| mdbx/batch.go | Adds the public Go API (GetBatchBuffer, Cursor.GetBatch) and C-memory buffer management. |
| mdbx/batch_test.go | Adds tests for correctness/allocations and a benchmark for scan performance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…op constraints, reset benchmark timers
…-on-error 2*(1<<28)*sizeof(MDBX_val) wraps a 32-bit size_t; 1<<20 pairs keeps the byte count below 2^25 everywhere and is still far beyond useful batch sizes. GetBatch doc now states the first n pairs stay valid on error.
…ndary paths Indexing past the pairs actually filled returned stale views from an earlier fill (possibly of an ended txn) instead of failing; at() now panics past buf.n. Adds exact-fill boundary and partial-on-error tests, documents *_MULTIPLE page granularity and write-txn view invalidation, and reorders the doc example to consume n before handling err.
…mpty key is NOTFOUND, not an error
An early EINVAL return left buf reporting entries from a previous fill, so Key/Val could hand out views of an already-ended transaction.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
mdbx/batch.go:56
- GetBatchBuffer.at() panics with “index out of range…” both for an out-of-range index and for use-after-Close (b.ptr == nil). Splitting the checks provides a clearer panic cause when the buffer has been closed.
if b.ptr == nil || i < 0 || i >= 2*b.n {
panic("mdbx: GetBatchBuffer: index out of range of the last GetBatch fill")
}
…ill count GetBatch passes an empty key/value to mdbx_cursor_get, so an op that expects one silently produced a plausible wrong answer instead of an error: (Set, Next) matched nothing and reported a clean EOF, (First, Set) ended the scan after one record the same way, and (SetRange, Next) rewound to the first key. Restrict opFirst/opNext to the ops that need no input — the start_op/turn_op sets libmdbx documents for mdbx_cursor_scan, plus the turn ops as opFirst so a scan can continue past its first batch — and return EINVAL for the rest. The allow-list also rejects GetCurrent as opNext (it would restream one record until the buffer filled) and out-of-range op values. Close now clears the last-fill count as well, so Key/Val panic with "use after Close" instead of handing out views of freed memory; at() reports that case separately from an out-of-range index. Tests: rejected-op table, reverse (Last, Prev) scan, DupSort (FirstDup, NextDup) scan, use-after-Close and out-of-fill panics. The partial-on-error test now provokes MDBX_INCOMPATIBLE with NextMultiple, which stays valid under the allow-list. Scan benchmark is unchanged: 36.6 ns/record for Get/Next vs 9.2 for GetBatch(256).
…ixture The rejected-op assertions checked IsErrnoSys(err, syscall.EINVAL), which only holds on POSIX: on Windows MDBX_EINVAL is ERROR_INVALID_PARAMETER, so every case failed the win job. Pin the rejection itself — an error, n=0, eof=false — as TestTxn_Reset_ReturnsError already does for the same reason. fillBatchDB uses fmt.Appendf, fixing the two modernize findings from lint.
… docs GetBatchBuffer uniquely owns a calloc allocation but was copyable, so `c := *buf` gave two values that free the same pointer. Add noCopy, as Cursor and Txn have; go vet now rejects the copy. The doc told callers to do ranged scans by positioning with Get and then batching with (GetCurrent, Next), and nothing tested it -- dropping GetCurrent from batchFirstOpOK broke the recipe with every test still green. TestCursor_GetBatch_Ranged covers it, and TestCursor_GetBatch_AcceptsAllTurnOps covers the turn ops the doc lists that no test reached. Doc corrections, none with runtime effect: - Key said Cursor.Get reports a nil key for FirstDup, LastDup, NextDup and PrevDup. cursor.go only nils it for the first two, and libmdbx fills it for all four. - PrevMultiple was missing from the unspecified-key list. It reaches fetch_multiple through cursor_sibling_left, which writes only data, so every pair after the first carries an empty key -- while the *_MULTIPLE note promised a key per pair. - Close said Key/Val slices point into the buffer's allocation. They view libmdbx's pages; castToBytes builds them over iov_base. Close invalidates later calls, not slices already returned. The refill/Close restriction is a conservative contract, now labelled as one. - The rejected-op list named "KeyTo/PairTo seeks", which are not identifiers here; the Go names are Key*/ExactKeyValue*/Pair*. - "rejected with EINVAL" now notes ERROR_INVALID_PARAMETER on Windows, matching how txn.go:464 words the same thing. - The MDBX_RESULT_TRUE comments in batch.go, mdbxgo.c and mdbxgo.h gave bound seeks as the example. e77127a made those ops rejected, so no op reaching the helper can produce RESULT_TRUE; it is kept as a defence and now says so.
awskii
left a comment
There was a problem hiding this comment.
51b23f3 covers the eight points from my last review. Three minor follow-ups inline.
51b23f3 left three defects of its own. TestCursor_GetBatch_AcceptsAllTurnOps claimed all turn ops but checked four of eight, and no start op beyond First and Last. Dropping PrevDup, PrevMultiple, LastDup or GetMultiple from the allow-lists left every test green. It is now TestCursor_GetBatch_AcceptsAllScanOps and drives every start and turn op the doc lists across a plain, a DupSort and a DupSort|DupFixed table; removing any of those four ops now fails it. The Close and Key docs contradicted each other: Close said returned slices survive it, Key said to treat them as invalid once Closed. The slices view libmdbx pages, not the buffer, so state that lifetime once and drop the conservative-contract sentence. The "(Last, Prev)" comment had been pushed onto the Ranged test's doc block; it is back above TestCursor_GetBatch_Reverse.
|
| scan | ns/record |
|---|---|
Get(Next) loop, this PR's baseline |
52.75 |
GetBatch, batch 64 |
10.29 |
GetBatch, batch 256 |
9.20 |
GetBatch, batch 1024 |
8.83 |
5.7x on the production platform, more than the 3.5x measured on darwin/arm64, because a cgo call costs more here (52.75 against 34.2 ns).
Erigon's cursor2iter.Next is Current() then advance(), which is GetCurrent plus Next: two cgo calls per record. A throwaway benchmark reproducing that shape, with and without copying each key and value:
| scan | count only | copy k,v |
|---|---|---|
| Erigon iterator shape | 104.55 | 94.84 |
Get(Next) loop |
52.38 | 51.19 |
GetBatch, batch 256 |
9.88 | 13.30 |
Against what Erigon runs today, batching is 10.6x on a bare loop and 7.1x with a per-record copy. Half of that needs no new API: the iterator re-fetches every record with GetCurrent after Next already returned it, and dropping that alone is 2x.
Where it would not help: a 30-second CPU profile of an Erigon execution workload shows mdbxgo_cursor_get_val at ~11% cumulative, but that time is B-tree search (cmp_lexical, search_branch_lexical, page_get_unchecked), which means seeks. GetBatch only speeds up sequential scans, and rejects seek ops.
… write-txn view and cursor-position limits - PrevMultiple off a single-value key (and GetCurrent on an empty table) returns MDBX_ENODATA; report it as eof instead of erroring the scan. - Key/Val views in a write txn last only until the next update: any Put/Del shifts the page under the batch's other views. - The cursor sits on the last stored pair after a fill; cursor ops in the handler hit the wrong record. - Scan-ops test now walks each op to eof, crosses DupFixed pages, and covers the single-value PrevMultiple case. - Note how mdbxgo_cursor_get_batch differs from libmdbx's mdbx_cursor_get_batch; trim the RESULT_TRUE comments.
Key(math.MinInt) and Val(math.MinInt) overflowed to slot 0 and 1 and returned the first record instead of panicking.
NextMultiple segfaulted on a fresh cursor over a single-value key, returned empty pages without DupFixed, and lost or repeated values when paired with a record op.


Scanning via
Get(Next)pays the fixed cgo overhead once per record.GetBatchmoves the loop into C: one call fills a reusable C-allocatedMDBX_valbuffer (never scanned for Go pointers),Key(i)/Val(i)return the usual zero-copy views, andeofdistinguishes exhaustion from buffer-full. Advancing ops only — there is no way to pass a search key, so for ranged scans position the cursor withGetfirst and batch with(GetCurrent, Next); DupSort works via(FirstDup, NextDup)etc.100k-record scan, darwin/arm64: 34.2 ns/record → 10.3 (batch 64) / 9.7 (batch 256+), ~3.5x. Includes correctness + no-allocs tests and the benchmark.